=begin pod

=TITLE role Callable

=SUBTITLE Invocable code object

    role Callable { ... }

Role for objects which support calling them. It's used in L<Block>,
L<Routine>, L<Sub>, L<Method>, L<Submethod> and L<Macro> types.

Callables can be stored in C<&>-sigiled containers, the default type constraint
of such a container is C<Callable>. A signature object can be used to
force a check against the signature of the Callable to be stored into the
container.

    my &a = {;}; # Empty block needs a semicolon
    my &b = -> {};
    my &c = sub () {};
    sub foo() {};
    my &d = &foo;
=for code :skip-test
my &f:(Int) = sub bar(Int) {}; # Not yet implemented
my &f:(Str) = -> Str {};       # Not yet implemented

=head1 Methods

=head2 method CALL-ME

    method CALL-ME(Callable:D $self: |arguments)

This method is required for postfix:«( )» and postfix:«.( )». It's what makes
an object actually call-able and needs to be overloaded to let a given object
act like a routine. If the object needs to be stored in a C<&>-sigiled
container, is has to implement Callable.

    class A does Callable {
        submethod CALL-ME(|c){ 'called' }
    }
    my &a = A;
    say a(); # OUTPUT: «called␤»

=head2 method Capture

Defined as:

    method Capture()

Throws C<X::Cannot::Capture>.

=head2 method assuming

    method assuming(Callable:D $self: |primers)

Returns a C<Callable> that implements the same behaviour as the
original, but has the values passed to .assuming already bound to the
corresponding parameters.

    my sub slow($n){ my $i = 0; $i++ while $i < $n; $i };

    # takes only one parameter and as such wont forward $n
    sub bench(&c){ c, now - ENTER now };

    say &slow.assuming(10000000).&bench; # OUTPUT: «(10000000 7.5508834)␤»

For a sub with arity greater than one, you can use C<Whatever> C<*> for all of the positional parameters that are not "assumed".

    sub first-and-last ( $first, $last ) {
        say "Name is $first $last";
    }

    my &surname-smith = &first-and-last.assuming( *, 'Smith' );

    &surname-smith.( 'Joe' ); # OUTPUT: «Name is Joe Smith␤»

You can handle any combination of assumed and not assumed positional parameters:

    sub longer-names ( $first, $middle, $last, $suffix ) {
        say "Name is $first $middle $last $suffix";
    }

    my &surname-public = &longer-names.assuming( *, *, 'Public', * );

    &surname-public.( 'Joe', 'Q.', 'Jr.'); # OUTPUT: «Name is Joe Q. Public Jr.␤»

Named parameters can be assumed as well:

    sub foo { say "$^a $^b $:foo $:bar" }
    &foo.assuming(13, :42foo)(24, :72bar); # OUTPUT: «13 24 42 72␤»

And you can use C<.assuming> on all types of L<Callables|/type/Callable>,
including L<Methods|/type/Method> and L<Blocks|/type/Block>:

    # We use a Whatever star for the invocant:
    my &comber = Str.^lookup('comb').assuming: *, /P \w+/;
    say comber 'Perl is awesome! Python is great! And PHP is OK too';
    # OUTPUT: «(Perl Python PHP)␤»

    my &learner = {
        "It took me $:months months to learn $^lang"
    }.assuming: 'Perl 6';
    say learner :6months;  # OUTPUT: «It took me 6 months to learn Perl 6␤»

=end pod

# vim: expandtab softtabstop=4 shiftwidth=4 ft=perl6
